MkDocs Installieren und ein erstes Projekt erstellen
MkDocs installieren
MkDocs benötigt die aktuelle Python Version und den Python Package Manager pip.
root:~# python --version
Python 3.8.2
root:~# pip --version
pip 20.0.2 from /usr/lib/python3/dist-packages/pip (python 3.8)
Wenn der pip Package Manager nicht installiert ist, wird er wie folgt installiert.
root:~# pip install --upgrade pip
Nun können wir MkDocs mit pip installieren.
root:~# pip install mkdocs
Nach der Installation, prüfen wir welche Version uns installiert wurde.
root:~# mkdocs --version
mkdocs, version 1.4.0 from /usr/local/lib/python3.8/dist-packages/mkdocs (Python 3.8)
Wenn wir das wie hier unter root installiert haben, wird mkdocs nach /usr/local/bin/ installiert.
root:~# which mkdocs
/usr/local/bin/mkdocs
Wird mkdocs als Benutzer installiert, würde es nach $HOME/.local/bin/ installiert werden. In diesem Fall sollte man diesen Pfad in die PATH Variable mit aufnehmen.
Als nächstes können wir noch optional das Material Theme installieren, welches mit vielen Features ausgestattet ist und auch noch sehr nice aussieht.
root:~# pip install mkdocs-material
Ein neues Projekt erstellen
Um ein neues Projekt zu erstellen, müssen wir einfach folgenden Befehl im Terminal eingeben.
root:~# mkdocs new myproject && cd myproject
INFO - Creating project directory: myproject
INFO - Writing config file: myproject/mkdocs.yml
INFO - Writing initial docs: myproject/docs/index.md
Im neu erstellen Projekt Verzeichnis, finden wir ein Verzeichnis docs/ in dem eine index.md Datei vorhanden ist. Weiterhin finden wir eine mkdocs.yml, wo die Einstellungen für unser Projekt definiert werden.
MkDocs kommt mit einem eingebetteten Webserver daher. Wenn wir im Projekt Verzeichnis sind, können wir der Server wie folgt starten. Die Dokumentation wäre dann unter http://127.0.0.1:8000/ erreichbar.
root:~/myproject# mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 0.09 seconds
INFO - [11:16:21] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [11:16:21] Serving on http://127.0.0.1:8000/
